% This is a latex file. It can be read as is if latex is not available.
\documentstyle{article}\begin{document}
%\newcommand{\kwd}[1]{\vb{#1}}
\newcommand{\kwd}[1]{{\tt #1}}
\parindent 0pt                  %no indent in first line of paragraph
\parskip .7em                   %vskip between paragraphs
\title{\bf 
        ELK EXTENSIONS INSTALLATION GUIDE
}
\author{
        J.P.Lewis\\
        NEC C\&C Research\\
        zilla@ccrl.nj.nec.com
}

\date{12 November 92}

\maketitle

This file has instructions for building the Elk extensions.
The building process is probably not foolproof at this point, 
so you should first look at the tutorial
examples to decide if you are interested in these extensions.
It is expected that the instructions may be unclear in places.  
Please send mail to zilla@ccrl.nj.nec.com if you have problems;
I may be reachable by phone at 609 951 2464 or 609 951 2441 
if there is no response from the e-mail address.

Warning: the following files from the standard Elk distribution
are written over during the installation of these extensions:
In src/, load.c, main.c, math.c, proc.c, stab.c, type.c, object.h.
In scm/, toplevel.

The build files for the extensions assume that the extensions
are located in contrib/zelk relative to the top level elk source
directory.  

\subsection*{Build Elk Without Extensions}
Please build the unmodified Elk first, 
in order to help isolate any problems which are caused by the extensions.

\subsection*{Build the Extensions}

In the remaining instructions TOP refers to the top level elk source directory
and ZELK refers to the directory TOP/contrib/zelk.

The extensions will be located in TOP/contrib/zelk.
If this directory does not already exist, cd to contrib and untar zelk.tar.

In TOP/Makefile, add contrib/zelk as the second target (after include),
and move the target lib/misc before the target src:
\begin{verbatim}
SUBDIRS=include\ 
    contrib/zelk\
        scripts\
    lib/misc\
        src\
        scm\
        lib/util\ 
        ....
\end{verbatim}

Copy or move the system configuration files in ZELK/config/ to TOP/config.

In TOP/config, link one of the XX-zelk files to system, for example,
\begin{verbatim}
    ln -s sun4-sunos4.1-cc-zelk system
\end{verbatim}
As of November 92 these extensions can be compiled on SUN/sparc
machines using cc, and on SGI/Irix4 machines also using cc.
On the Sun, the couple of asm() statements which implement the foreign 
function interface (forfunc.c) do not compile correctly with gcc.
The vector extensions (fvector.c) require an ANSI C compiler, 
however, and so must either be left out or be compiled with gcc.
This choice is selected as indicated below. 

Customize this system file in the same way as with the normal elk installation.
Then edit the end of the file, following the line
\begin{verbatim}
    ################ zelk extensions stuff ################
    # set this to the elk source directory
    elktop=/usr/local/pub/src/elk2

    # include vector extensions? They require an ansi compiler; 
    # select one of 'fvectorgcc.o', 'fvectorsgi.o', or 'fvectornone.o'  
    fvector=fvectorgcc.o
\end{verbatim}
Here, indicate the path of the top level elk source directory,
and whether you want to include the elk vector extensions.
The vector extensions require an ANSI compiler; 
on the Sun the availability of gcc is assumed.

Copy ZELK/scm/.elkrc to your home directory. Customize this file later.

Now `make', and then `make install'.

\subsection*{Test the Extensions}
Some simple tests which will indicate if the extensions are working:

\begin{verbatim}
  (apropos "os-")
\end{verbatim}
This should list shell or operating system-related functions linked
through the foreign function interface.

\begin{verbatim}
  (os-timestring (os-filemodtime "/etc/passwd"))
\end{verbatim}
This should return the last-modified date of the indicated file.
It indicates that the foreign function interface is working.

\begin{verbatim}
  (apropos "v-")
\end{verbatim}
This should list the vector extension routines, if they were selected.

\begin{verbatim}
  (v-+ 10. (v-index 5))  => (% 10.0 11.0 12.0 13.0 14.0)
\end{verbatim}
Indicates the vector extensions are working.

\begin{verbatim}
  (load "shell.e")
\end{verbatim}
Test that the scheme library files included the extension 
are found on the load path.

\begin{verbatim}
  (declare-shell ls rwho cat)
  (ls)
  (ls "/tmp")
\end{verbatim}
Test the declare-shell construct from shell.e.

\subsection*{Guide to the Files}
\begin{verbatim}

In contrib/zelk/
config          contains system configuration files which should be copied 
                into TOP/config.

scm             contains sample scheme files using the elk extensions
scm/toplevel,basics  
                Toplevel is the file which Elk loads when it runs;
                Elk behavior can be customized by changing this.
                Toplevel has been split into toplevel and basics for
                reasons relating to the running of shell files;
                see comments in these files.
                Toplevel is copied into Elk/scm and the default toplevel
                is renamed to toplevel.old. 
scm/.elkrc      The new toplevel/basics startup also tries to load a file
                named .elkrc from your home directory ($HOME).  This
                is a sample of such a file; copy it to your $HOME 
                and modify it.

src-zelk        The source for the extensions
        forfunc.c  The foreign function interface and Sparc code
        FORMIPS.c  SGI/MIPS version of the foreign function interface.
                   This file is *included* in forfunc.c.
        MIPSASM.s  A small assembler file for the SGI/MIPS FFI.
        farray.c   Implements "foreign arrays" (see tutorial).
        forpkg.c   "foreign libraries".  
        fvector.c  The APL-like vector routines.
        forgl.c    Foreign function bindings to the SGI GL graphics library.
        peekpoke.c Low-level peek/poke using foreign arrays.  The file
                   fstruct.e implements C structures in scheme using this.
        zelk.c     Routines and foreign function bindings for the "elk
                   shell".
        rtltest.c  A sample foreign library
                   (rtl is mnemonic for run-time-load).
                   
src-elk         Modified versions of a few files from the elk src/ directory.

src-zlib        Source for libZ.a - some library routines 
                (not specific to scheme) that are used by the extensions. 
                
include         Include files used by the extensions and library routines.
        theusual.h This file attempts to isolate all system dependencies;
                   it is a mess consequently.
        zlib.h     Prototypes for the library routines in src-zlib.
\end{verbatim}

\subsection*{Troubleshooting and Details}

Since the make may not work, 
a guide to what it is trying to do will be given:

The second target in the top level make is contrib/zelk.
The make cd's to this directory and executes the Makefile there.

The contrib/zelk Makefile does these things:
\begin{itemize}

\item
runs the shell file build to make Makefile.local, 
which then:

\item
Copies a modified version of the scheme toplevel file to TOP/scm,
and copies a few new scheme source files to the scheme library
directory (scheme\_dir in config/site).

\item
Copies a few modified elk C source files into TOP/src:
load.c,main.c, math.c, proc.c, type.c, object.h.
The modifications include adding hooks for the foreign function interface
(proc.c, object.h),
changes related to dynamic loading and 'foreign libraries'
(stab.c, load.c),
changes in the behavior of math (which you might want to revoke) (math.c),
and initialization of the extensions (main.c).

\item
Compiles the extension sources in ZELK/src-zelk.
The extensions are linked using ld -r into one large grouped binary file 
ZELK/Zelk.o, which is later linked with Elk.  

\item
Builds libZ.a.  This is a library of C routines (not Elk specific)
in ZELK/src-zlib which are used by the extension sources.

\end{itemize}

Then the Makefile in TOP/src compiles the elk kernel 
and links it with Zelk.o and libZ.a.
Two files in TOP/lib/misc (unix.o and chdir.o) are now pre-linked
in the kernel, rather than being loaded on demand, since they
are used in the ``elk shell''.  This is why the lib/misc target must be
before the src/ target in the top level Makefile.

On SGI machines the routines in libZ.a usually cause 
``GP relocation errors'' at link time, possibly because 
they use a larger-than-normal amount of global/static storage.
These errors go away if *everything* is compiled with -G0.
The proper -G value (other than 0) is not known to me.

The sparc foreign function interface in forfunc.c must 
not be compiled with -O, since optimization will generate
incorrect code in programs with asm() statements.

\subsection*{Coding}
Modifications to the original Elk source are flagged by an 
\#if and comment in the source-
\begin{verbatim}
        #if ZELK 
        .... /*&zilla...*/
\end{verbatim}
Compiling with ZELK turned off has not fully tested.

The extension source files include a file theusual.h.
I attempted to move all messy non-portable C details into this file;
the source itself has fewer \#ifdefs as a result, 
but this file is a mess.  You may need to change some of it.

The extension sources use several macros from theusual.h.
The macro Zproto((prototype)) appears in function prototypes;
it is the same as the P\_ macro in the Elk kernel sources.
In ANSI C it expands into (prototype); in K\&R C it expands into ().
The macro Ztrace((printf-args)) expands into printf(printf-args) if
\begin{verbatim}
        #define ztrace
\end{verbatim}
appears before theusual.h or zelk.h is included.

The define ZILLAONLY appears in zelk.h; this brackets a few things
which are specific to the author's installation and are
not of general interest.

\end{document}
